/*
 * Copyright 2009 Armando Blancas
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package taskgraph.ports;

import java.io.IOException;

/**
 * An output interface to a Channel of object references as elements.
 * 
 * @author Armando Blancas
 * @param <E> The type of elements that go through a channel.
 */
public interface OutputPort<E> extends Port {
	
    /**
     * Writes an element to this output pipe.
     * 
     * @param e The element to be put into the channel.
     * @return  This output port.
     * @throws IOException  If an I/O error occurs.
     */
	OutputPort<E> write(E e) throws IOException;

    /**
     * Writes to the channel all the elements in array {@code e}.
     * If {@code e} is {@code null}, a {@code NullPointerException} is thrown. 
     * If {@code e.length} is zero, then no elements are written. Otherwise, 
     * the element {@code e[0]} is written first, then {@code e[1]}, and 
     * so on; the last element written is {@code e[e.length-1]}.
     *
     * @param e The array of elements to be put into this channel.
     * @return  This output port.
     * @throws IOException If an I/O error occurs.
     */
	OutputPort<E> write(E[] e) throws IOException;

    /**
     * Writes <code>len</code> elements from array <code>e</code>, in order, 
     * to the channel. If <code>e</code> is <code>null</code>, a <code>
     * NullPointerException</code> is thrown.  If <code>off</code> is negative,
     * or <code>len</code> is negative, or <code>off+len</code> is greater than
     * the length of the array <code>e</code>, then an <code>
     * IndexOutOfBoundsException</code> is thrown.  If <code>len</code> is zero,
     * then no elements are written. Otherwise, the element 
     * <code>e[off]</code> is written first, then <code>e[off+1]</code>, and so
     * on; the last element  written is <code>e[off+len-1]</code>.
     *
     * @param e The array of elements to be put into this channel.
     * @param off The start offset in the array.
     * @param len The number of elements to write.
     * @return  This output port.
     * @throws IOException If an I/O error occurs.
     */
	OutputPort<E> write(E[] e, int off, int len) throws IOException;

}
